Claude Code 命令与技巧全览
这篇是我自己学 Claude Code 时整理的速查手册。所有内容都对照了 官方文档 和本机 claude --help 的输出,写作时的版本是 v2.1.310(2026 年 10 月)。
- Claude Code 更新很快,几乎每周都有命令增删,所以以你本机为准:在会话里敲
/能看到当前可用的全部命令,claude --help列出全部启动参数,/release-notes看更新日志。 - 下文表格里标 ★ 的是日常最常用的命令和快捷键,初学先记这些就够了。
- 不是每个命令每个人都有。可用与否取决于平台、套餐和登录方式,比如
/desktop只在 macOS 和 x64 Windows 且用 Claude 订阅登录时出现,/upgrade在 Enterprise 套餐下不显示。
启动:命令行参数
最常用的几种启动方式
| 命令 | 作用 |
|---|---|
claude ★ | 在当前目录启动交互式会话 |
claude "解释一下这个项目" | 启动交互式会话,并把这句话作为第一条消息 |
claude -p "查询" ★ | 非交互模式:输出结果后直接退出,适合脚本和管道 |
cat log.txt | claude -p "解释这个报错" | 把管道内容喂给 Claude |
claude -c ★ | 继续当前目录下最近一次对话 |
claude -r ★ | 打开会话选择器;claude -r auth-refactor 按名字或 ID 恢复 |
claude -n 名字 | 给本次会话起名,显示在输入框、/resume 列表和终端标题里 |
claude -w feature-auth ★ | 在 .claude/worktrees/feature-auth 新建一个 git worktree 并在里面启动 |
claude --bg "任务" | 在后台启动会话并立即返回,打印的 ID 给 claude attach / logs / stop 用 |
常用参数
| 参数 | 作用 |
|---|---|
--model <model> ★ | 指定模型,可以写别名(fable、opus、sonnet)或完整模型名 |
--effort <level> | 推理强度:low、medium、high、xhigh、max |
--permission-mode <mode> ★ | 启动时的权限模式:acceptEdits、auto、bypassPermissions、manual、dontAsk、plan |
--add-dir <dirs...> | 额外允许访问的目录 |
--allowedTools / --disallowedTools | 放行 / 禁止某些工具,如 "Bash(git *) Edit" |
--tools <tools...> | 限定可用的内置工具集合,"" 表示全部禁用 |
--agent <agent> | 让整个会话以某个子代理的身份运行 |
--append-system-prompt <prompt> | 在默认系统提示后追加内容;--system-prompt 则是整体替换 |
--mcp-config <configs...> | 从 JSON 文件或字符串加载 MCP 服务器;配合 --strict-mcp-config 只用这些 |
--settings <file-or-json> | 本次会话额外加载一份设置 |
--fork-session | 配合 -r / -c,恢复时生成新的会话 ID,原会话不动 |
--from-pr [value] | 恢复与某个 PR 关联的会话 |
--chrome / --ide | 启用 Claude in Chrome / 启动时自动连接 IDE |
-d, --debug [filter] | 调试模式,可按类别过滤,如 --debug=hooks,mcp |
--safe-mode | 关掉所有自定义(CLAUDE.md、skills、插件、hooks、MCP 等)启动,排查配置问题用 |
--bare | 极简模式:跳过 hooks、插件、自动记忆、CLAUDE.md 自动发现等,脚本里启动更快 |
--dangerously-skip-permissions | 跳过所有权限检查。官方建议只在没有外网的沙箱里用 |
只对 -p 生效的参数:--output-format(text / json / stream-json)、--input-format、--json-schema(结构化输出)、--max-budget-usd(花费上限)、--no-session-persistence、--include-partial-messages。
子命令
| 子命令 | 作用 |
|---|---|
claude update ★ | 检查并安装更新(别名 upgrade) |
claude install [target] | 安装原生版本,可指定 stable、latest 或具体版本号 |
claude doctor | 检查安装健康状况;会话里的 /doctor 更全,还能帮你修 |
claude mcp ★ | 管理 MCP 服务器,见下文 |
claude plugin | 管理插件 |
claude auth | 管理登录认证 |
claude setup-token | 生成长期有效的认证 token(需要 Claude 订阅) |
claude agents | 列出和管理后台会话 |
claude attach <id> | 把一个后台会话接回当前终端 |
claude logs <id> | 打印后台会话最近的输出 |
claude stop <id> | 停止后台会话,对话保留 |
claude rm <id> | 删除后台会话(安全时连 worktree 一起删) |
claude ultrareview [target] | 在云端跑多代理代码评审 |
claude import [source] | 从别的 AI 编码工具导入配置 |
claude purge [path] | 删除某个项目的全部 Claude Code 状态(对话记录、文件历史等) |
子命令拼错时,Claude Code 会提示最接近的那个并退出,比如 claude udpate 会打印 Did you mean claude update?。
输入框:前缀与多行
开头字符决定输入的含义
| 输入 | 含义 |
|---|---|
/ 开头 ★ | 命令或 skill。只有出现在消息开头才会执行,后面的文字是它的参数 |
! 开头 ★ | Shell 模式:直接跑命令,不经过 Claude 审批,命令和输出进入上下文,Claude 会接着解读 |
@ ★ | 引用文件路径(带自动补全),也可以 @ 目录、@server:resource 引用 MCP 资源 |
: | 输入 :name: 插入 emoji |
空输入框里按 ? | 打开快捷键帮助面板 |
几个细节:
! npm test跑完后 Claude 会自动解释输出,消耗等同发一条普通消息。只想把输出放进上下文、不要回复,可在settings.json里把respondToBashCommands设为false。- Shell 模式下用
Tab可以从当前项目以前的!命令里补全;输入带/的路径会弹出文件补全。退出 Shell 模式:空输入时按Esc、Backspace或Ctrl+U。 @src/utils/auth.js会把文件内容直接放进对话(在 Read 工具的 token 上限内,默认 25,000 token;超过 256KB 的文本文件不会放进去)。- 一条消息可以叠多个 skill:
/write-tests /fix-issue 123会加载两个 skill,123作为参数传给每一个,最多叠六个。 - 在句子中间敲
/也有补全(比如跑完测试再 /com),但只有开头的命令会被执行。
多行输入
| 方式 | 说明 |
|---|---|
\ + Enter ★ | 所有终端都能用 |
Ctrl+J | 所有终端都能用,不需要配置 |
Shift+Enter ★ | iTerm2、WezTerm、Ghostty、Kitty、Warp、Apple Terminal、Windows Terminal 原生支持;VS Code、Cursor 等可用 /terminal-setup 装上 |
Option+Enter | macOS 上把 Option 设成 Meta 键之后可用 |
| 直接粘贴 | 适合代码块和日志 |
图片
三种方式:把图片拖进窗口;复制后用 Ctrl+V 粘贴(iTerm2 里是 Cmd+V,Windows/WSL 是 Alt+V);或者直接在消息里写图片路径。粘贴后会出现一个 [Image #N] 标记。
快捷键
macOS 用户注意:Alt+B、Alt+F、Alt+D、Alt+Y、Alt+P 这类快捷键需要在终端里把 Option 设为 Meta 键。
常规控制
| 快捷键 | 作用 |
|---|---|
Esc ★ | 打断 Claude 当前的回复或工具调用,已经做的工作保留;有对话框时关闭对话框 |
Esc Esc ★ | 输入框有字时:清空并存进历史(按 Up 能找回);输入框为空时:打开回退(rewind)菜单 |
Ctrl+C ★ | 有任务在跑时打断;没有时第一下清空输入,第二下退出 |
Ctrl+D | 退出(按两下,800ms 内);输入框有字时是向后删一个字符 |
Shift+Tab ★ | 循环切换权限模式(Windows 某些情况下是 Alt+M) |
Ctrl+B ★ | 把正在运行的 Bash 命令或代理放到后台(tmux 里要按两次) |
Ctrl+O ★ | 打开 / 关闭对话详情视图,能看到每次工具调用的细节 |
Ctrl+T | 显示 / 隐藏 Claude 的任务清单 |
Ctrl+R ★ | 反向搜索输入历史 |
Ctrl+G 或 Ctrl+X Ctrl+E ★ | 用默认编辑器编辑当前输入(写长提示词很好用) |
Ctrl+S | 暂存当前输入并清空;在空输入框再按一次恢复 |
Ctrl+L | 重绘屏幕,界面花了的时候用 |
Ctrl+V ★ | 粘贴图片 |
Ctrl+Z | 挂起到 shell(仅 Unix),用 fg 回来 |
Ctrl+Enter 或 Ctrl+X Ctrl+S | 立即发送排队中的消息 |
Ctrl+X Ctrl+K | 停止本会话所有后台子代理(3 秒内按两次确认) |
Option+P / Alt+P | 切换模型,不清空输入 |
Option+T / Alt+T | 开关扩展思考(对 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 无效,它们始终开启) |
Option+O / Alt+O | 开关 fast 模式 |
Up / Down | 在多行输入里移动光标,到首行 / 末行后再按就是翻历史 |
Tab | 接受补全建议 |
文本编辑
| 快捷键 | 作用 |
|---|---|
Ctrl+A / Ctrl+E | 移到行首 / 行尾 |
Ctrl+K | 删到行尾 |
Ctrl+U | 删到行首(macOS 终端里 Cmd+Backspace 映射到它) |
Ctrl+W | 向前删到上一个空白,一下删掉一整个路径或 --flag=value |
Ctrl+Y | 粘贴刚才删掉的文字;之后按 Alt+Y 循环更早的删除内容 |
Alt+B / Alt+F | 按词后退 / 前进 |
Alt+D | 删到词尾 |
Ctrl+_ | 撤销上一次输入编辑 |
Vim 模式和自定义快捷键
/vim命令在 v2.1.92 已经移除,现在从/config→ Editor mode 切换。支持常见的 NORMAL / INSERT / VISUAL 操作:hjkl、w/b/e、dd、ciw、yy/p、u、.等。NORMAL 模式下按/是历史搜索,不是命令菜单。/keybindings打开~/.claude/keybindings.json,可以改绑任意快捷键。
Claude 干活时也能继续打字
Claude 在工作时按 Enter,消息会排队,不会打断当前这一轮。普通消息会在当前这批工具调用结束后、同一轮里就交给 Claude;命令和 ! 命令会等这一轮结束再按顺序执行。从输入框第一行按 Up 能把排队的内容收回来修改。
斜杠命令:全部清单
这里收了当前文档里的全部内置命令。标 (skill) 的是内置 skill:本质是一段交给 Claude 的提示词,和你自己写的 skill 一样运作。参数里 <arg> 是必填,[arg] 是可选。
会话与上下文
| 命令 | 作用 |
|---|---|
/clear [name] ★ | 开新对话、清空上下文(项目记忆保留)。别名 /reset、/new |
/compact [instructions] ★ | 把对话压缩成摘要以腾出上下文,可以附加摘要重点,如 /compact 重点保留 API 改动 |
/autocompact [auto|<tokens>] | 设置自动压缩的触发窗口,如 500k |
/context [all] ★ | 用彩色网格可视化上下文占用,并给出优化建议 |
/resume [session] ★ | 恢复之前的对话,不带参数打开选择器。别名 /continue |
/rename [name] | 重命名当前会话;不带参数则根据对话自动起名 |
/branch [name] | 从当前位置分出一个对话分支并切过去,原对话可用 /resume 回去 |
/fork [prompt] | 把当前对话复制成一个新的后台会话,你留在这里继续 |
/subtask <task> | 派一个继承完整对话的后台子代理去做事,结果会回到当前对话 |
/rewind ★ | 回退代码和 / 或对话到某个检查点,或对某段对话做摘要。别名 /checkpoint、/undo |
/btw [question] ★ | 问个旁支问题,问答不进入对话历史;Claude 工作时也能问 |
/recap | 生成当前会话的一句话摘要 |
/export [filename] | 把对话导出为纯文本 |
/copy [N] | 复制最近一条回复(/copy 2 是倒数第二条),有代码块时可挑选;按 w 写入文件 |
/diff ★ | 查看工作区改动,包括 Claude 到目前为止的编辑 |
/exit | 退出。别名 /quit |
模型与推理
| 命令 | 作用 |
|---|---|
/model [model] ★ | 切换模型并存为默认;选择器里按 s 只对本会话生效,左右方向键调推理强度 |
/effort [level|auto|status|ultracode [on|off]] | 设置推理强度;max 只对本会话有效 |
/fast [on|off] | 开关 fast 模式 |
/advisor [model|off] | 开关 advisor:关键时刻向第二个模型请教 |
/plan [description] ★ | 进入计划模式,可直接带上任务,如 /plan 修复登录 bug |
/goal [condition|clear] | 设一个目标,Claude 会跨多轮持续工作直到条件满足 |
权限与安全
| 命令 | 作用 |
|---|---|
/permissions ★ | 管理 allow / ask / deny 规则和工作目录。别名 /allowed-tools |
/sandbox | 开关沙箱模式(仅支持的平台) |
/auto-mode-setup | 根据项目和最近的会话起草 auto 模式的环境描述,审阅后保存 |
/fewer-permission-prompts | (skill) 扫描历史里常用的只读命令,生成 allowlist 写进项目 .claude/settings.json |
/security-review | 检查当前分支相对 origin 默认分支的改动有没有安全漏洞(需要 origin remote) |
项目配置与记忆
| 命令 | 作用 |
|---|---|
/init ★ | 分析代码库,生成初始 CLAUDE.md;已有时给出改进建议。设 CLAUDE_CODE_NEW_INIT=1 走交互式流程,顺带配置 skills 和 hooks |
/memory ★ | 编辑 CLAUDE.md,开关 / 查看自动记忆 |
/config [key=value ...] ★ | 打开设置面板,或直接 /config theme=dark、/config model=sonnet。别名 /settings |
/add-dir <path> | 给本会话添加工作目录 |
/cd <path> | 把会话移到另一个目录,对话保留 |
/hooks | 查看 hook 配置 |
/statusline | 配置状态栏,描述你要什么或不带参数从 shell 提示符自动生成 |
/output-style [style] | 列出或切换输出风格 |
/theme | 切换配色主题,可新建自定义主题 |
/keybindings | 打开快捷键配置文件 |
/terminal-setup | 为当前终端装 Shift+Enter 换行等配置 |
/tui [default|fullscreen] | 切换渲染器,fullscreen 是无闪烁的全屏模式 |
/focus | 全屏模式下的精简视图:只看最后的提问、工具调用摘要和最终回复 |
/scroll-speed | 全屏模式下调整滚轮速度 |
/color [color|default] | 设置输入栏颜色 |
/update-config [request] | (skill) 用自然语言描述设置改动,Claude 去改对应的 settings.json |
/import [codex|gemini|cursor] | 从 Codex、Gemini CLI、Cursor 导入配置 |
扩展:skills、插件、MCP、子代理
| 命令 | 作用 |
|---|---|
/skills ★ | 列出可用 skill,按 t 按 token 数排序,空格 / 回车切换可见性 |
/reload-skills | 重新扫描 skill 目录,不用重启 |
/skill-doctor | 看每个 skill 占多少上下文、用了多少次 |
/plugin [subcommand] | 管理插件:list、install、enable、disable 等 |
/reload-plugins [--force] | 重新加载插件 |
/mcp ★ | 管理 MCP 连接和 OAuth;/mcp reconnect all 重连所有失败的服务器 |
/agents | 现在只打印一句提示:让 Claude 帮你建子代理,或直接编辑 .claude/agents/(v2.1.197 及以前是交互界面) |
/list-agents | 列出可以发消息的子代理和其他会话(需要开启跨会话消息)。别名 /peers |
/plugin-authoring | 加载编写 mod 的参考资料 |
/workflow-authoring | (skill) 加载编写动态 workflow 脚本的参考 |
代码评审与验证
| 命令 | 作用 |
|---|---|
/code-review [level] [--fix] [--comment] [target] ★ | (skill) 检查当前 diff 的正确性问题;--fix 直接修,--comment 发到 PR,ultra 走云端深度评审。可传 PR 号、分支或路径。别名 /review |
/ultrareview [PR or branch] | 云端多代理深度评审,推荐写法是 /code-review ultra |
/simplify [target] | (skill) 四个代理并行检查改动里可复用、可简化、可提效的地方并直接改,不找 bug |
/verify | (skill) 构建并实际运行应用来确认改动生效,不只看测试 |
/run | (skill) 启动并操作你的应用,亲眼看到改动 |
/run-skill-generator | (skill) 为项目生成一个教 /run、/verify 怎么启动应用的 skill |
/autofix-pr [prompt] | 开一个云端会话盯住当前分支的 PR,CI 挂了或有评论时自动推修复 |
并行、后台与定时
| 命令 | 作用 |
|---|---|
/tasks ★ | 查看和管理本会话的后台任务(包括已完成的子代理)。别名 /bashes |
/background [prompt] | 把整个会话转到后台运行,释放终端。别名 /bg |
/stop | 停止当前接入的后台会话 |
/batch <instruction> | (skill) 大规模改动:拆成 5 到 30 个独立单元,每个在独立 worktree 里由后台子代理完成 |
/loop [interval] [prompt] | (skill) 会话开着期间定时重复执行,如 /loop 5m 看看部署完了没;不写间隔则由 Claude 自己掌握节奏 |
/schedule [description] | 创建 / 管理云端定时任务。别名 /routines |
/workflows | 查看、暂停、恢复 workflow 的运行进度 |
/deep-research <question> | 内置 workflow:并行搜索、交叉核对来源,生成带引用的报告 |
跨设备与云端
| 命令 | 作用 |
|---|---|
/remote-control | 让本会话可以从 claude.ai 远程继续。别名 /rc |
/teleport | 把云端会话拉到本地终端。别名 /tp |
/desktop | 在桌面 App 里继续当前会话。别名 /app |
/remote-env | 选择云端会话的默认环境 |
/web-setup | 用本地 gh 凭据为云端会话连接 GitHub |
/mobile | 显示下载手机 App 的二维码。别名 /ios、/android |
账号、用量与诊断
| 命令 | 作用 |
|---|---|
/login / /logout | 登录 / 登出 Anthropic 账号 |
/status | 版本、模型、账号、连接状态 |
/usage ★ | 本次花费、套餐用量、活动统计。别名 /cost、/stats |
/rate-limit-options | 撞到用量上限时的选项:等待自动继续、加购额度或升级 |
/usage-credits | 配置用量额度(原 /extra-usage) |
/upgrade | 打开升级套餐页面 |
/privacy-settings | 隐私设置(Pro、Max) |
/insights | 生成一份分析你近期使用习惯的 HTML 报告 |
/doctor | (skill) 诊断安装、设置、扩展和 CLAUDE.md 问题,确认后帮你修;/doctor prompt-audit 审查指令文件里过时或冲突的内容。别名 /checkup |
/debug [description] | (skill) 开启调试日志并帮你分析 |
/heapdump | 导出内存快照排查内存问题(菜单里隐藏,要打全名) |
/bug [report] | 报 bug,发送前会让你确认附带多少会话内容。别名 /share |
/feedback [report] | 发产品反馈 |
/release-notes | 查看更新日志 |
/help ★ | 帮助和命令列表 |
集成与其他
| 命令 | 作用 |
|---|---|
/ide | 管理 IDE 集成 |
/chrome | Claude in Chrome 设置 |
/claude-in-chrome [task] | (skill) 让 Claude 在浏览器里执行任务 |
/install-github-app | 为仓库安装 Claude GitHub App,可选配置 GitHub Actions |
/install-slack-app | 安装 Claude Slack App |
/claude-api [subcommand] | (skill) 加载 Claude API / Managed Agents 参考资料 |
/voice [hold|tap|off] | 语音输入 |
/team-onboarding | 根据你过去 30 天的使用记录生成团队上手指南 |
/powerup | 交互式小课程,带动画演示,用来发现功能 |
/artifacts、/design、/slides、/dataviz 等 | 发布网页 Artifact、画设计稿、做幻灯片、图表设计指引(需要账号支持 Artifacts) |
/setup-bedrock / /setup-vertex | 配置第三方云平台(设置对应环境变量后才出现) |
/passes、/stickers、/radio | 送朋友试用、订贴纸、开 lo-fi 电台 |
已移除的命令:/vim(用 /config)、/pr-comments(直接让 Claude 去看 PR 评论)、/ultraplan(用计划模式)。
权限模式
Shift+Tab 循环切换,状态栏会显示当前模式。
| 模式 | 不问就能做的事 | 适合 |
|---|---|---|
default(界面上叫 Manual) | 只有读取 | 每一步都要自己过目 |
acceptEdits | 读取、改文件、常见文件系统命令(mkdir、mv、cp 等) | 边看边迭代 |
plan | 只读探索,不改源码,写出计划等你批准 | 动手前先摸清代码库 |
auto | 全部,但有一个独立的分类器模型在后台审查每个动作 | 长任务、不想被频繁打断 |
dontAsk | 工作目录内的读取和预先放行的工具,其他一律拒绝 | CI 和脚本 |
bypassPermissions | 全部 | 只在隔离的容器 / 虚拟机里用 |
要点:
- v2.1.283 起,交互式终端会话默认就从
auto模式启动。claude -p在没有任何设置指定模式时以 Manual 模式启动(v2.1.302 起)。 - 循环顺序是
default→acceptEdits→plan,之后是可选的bypassPermissions和auto。dontAsk不在循环里,只能用--permission-mode dontAsk指定。 - 计划写好后可以选:批准并进入 auto 模式、批准但每次编辑手动确认、或者继续改计划。批准前按
Ctrl+G能在编辑器里直接改计划。 - deny 规则在所有模式下都生效,包括
bypassPermissions。
权限规则
规则写在 settings.json 的 permissions 里,格式是 Tool 或 Tool(specifier):
{
"permissions": {
"allow": ["Bash(npm run *)", "Bash(git commit *)"],
"deny": ["Bash(git push *)", "Read(./.env)", "Read(./secrets/**)"]
}
}- 判定顺序是 deny → ask → allow,先命中谁算谁,跟具体程度无关。所以宽泛的 deny 会压过精确的 allow。
*要放在子命令后面:Bash(git log *)只放行git log,Bash(git *)放行所有 git 命令。Bash(ls *)不匹配lsof(星号前的空格是规则的一部分),Bash(ls*)则会匹配。- 只写工具名的 deny(如
Bash)会把整个工具从 Claude 的视野里拿掉。 .claudeignore没有任何作用,要屏蔽文件请写Read的 deny 规则。Read/Edit规则只管 Claude 的文件工具和它能识别的cat、head之类命令,挡不住一个自己去读文件的 Python 脚本。要系统级隔离得开沙箱(/sandbox)。- 权限提示里选「Yes, and don't ask again」时,Bash 命令和域名规则会存进仓库根目录的
.claude/settings.local.json;文件修改的放行只到本次会话结束。
设置文件的优先级
从高到低:组织下发的 managed 设置 → 命令行 --settings → .claude/settings.local.json(个人、本项目)→ .claude/settings.json(团队共享,提交到 git)→ ~/.claude/settings.json(个人、所有项目)。像 permissions.allow 这种列表会在各层之间合并,而不是互相覆盖。
记忆:CLAUDE.md 与自动记忆
每个会话都从空白上下文开始,跨会话靠两样东西:你写的 CLAUDE.md,和 Claude 自己记的自动记忆。两者都只是放进上下文的文字,Claude 不保证照做;真要拦住某个动作,得用 hook 或权限规则。
CLAUDE.md 放在哪
| 范围 | 位置 | 谁能看到 |
|---|---|---|
| 组织 | macOS 是 /Library/Application Support/ClaudeCode/CLAUDE.md | 全组织 |
| 用户 | ~/.claude/CLAUDE.md | 你自己,所有项目 |
| 项目 | ./CLAUDE.md 或 ./.claude/CLAUDE.md | 团队,提交到 git |
| 本地 | ./CLAUDE.local.md | 你自己,本项目,记得加进 .gitignore |
- 启动时会加载当前目录及所有上级目录的
CLAUDE.md,全部拼接起来而不是互相覆盖,越靠近工作目录的越后读到。子目录里的CLAUDE.md要等 Claude 读写那个子目录下的文件时才加载。 - 用
@path/to/file可以导入其他文件,比如参见 @README 和 @package.json,最多递归四层。写在反引号里的@README不会被导入。 - 块级 HTML 注释
<!-- ... -->会在注入前被剥掉,适合给人看的备注。 - 跑
/context能在 Memory files 下确认哪些文件加载了。 - 如果仓库只有
AGENTS.md,Claude Code 也能读它。
什么该写进 CLAUDE.md
官方的判断标准:同样的错误 Claude 犯第二次时;code review 抓到 Claude 本该知道的事时;你发现自己在重复上次会话说过的纠正时。只写每个会话都该知道的事实,比如构建命令、约定、目录结构。多步骤流程或只对某块代码有用的内容,改成 skill 或者按路径生效的规则。
太长的 CLAUDE.md 会被「看漏」。官方建议狠狠删:Claude 不写也能做对的,就删掉,或者改成 hook。
按路径生效的规则
在 .claude/rules/ 下放 markdown 文件,加上 paths 就只在 Claude 碰到匹配文件时才加载:
---
paths:
- "src/api/**/*.ts"
---
# API 开发规则
- 所有接口都要做输入校验没有 paths 的规则在启动时就加载,优先级和 .claude/CLAUDE.md 相同。
自动记忆
Claude 会根据你的纠正和偏好自己记笔记,存在 ~/.claude/projects/<project>/memory/,同一个 git 仓库的所有 worktree 共享一份。MEMORY.md 是索引,每次会话加载前 200 行或 25KB;具体条目放在单独的文件里,用到时才读。看到「Saved 2 memories」就是它在写。用 /memory 查看和开关,或者设 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 关闭。只存在本机,不跨机器同步。
检查点与回退
每条开启新一轮的消息都会自动建一个检查点。按两下 Esc(输入框为空时)或 /rewind 打开回退菜单,选一条历史消息后可以:
- Restore code and conversation:代码和对话都回到那时
- Restore conversation:只回退对话,代码保留现状
- Restore code:只回退代码,对话保留
- Summarize from here / up to here:把那之后 / 之前的对话压成摘要,相当于定向的
/compact
检查点随对话保存,关掉终端、之后 /resume 回来还能回退。所以可以大胆让 Claude 尝试有风险的方案,不行就退回去。
局限要记住:
- 只有 Bash 改过的文件不受追踪(
rm、mv之类的副作用退不回来)。 - 子代理的编辑通常不会被恢复。
- 你在外面手动改的、其他会话改的,也不追踪。
- 符号链接和硬链接文件会被跳过,pnpm 硬链接进来的文件就属于这种。
- 检查点只管会话内的快速恢复,长期的版本历史还是靠 git。
Skills:自定义命令
Skill 就是一个带 frontmatter 的 SKILL.md。旧的 .claude/commands/xxx.md 仍然有效,和 .claude/skills/xxx/SKILL.md 一样都会生成 /xxx 命令,但新写的推荐用 skill(可以带附属文件)。
| 位置 | 路径 | 生效范围 |
|---|---|---|
| 个人 | ~/.claude/skills/<name>/SKILL.md | 本机所有项目 |
| 项目 | .claude/skills/<name>/SKILL.md | 本仓库,提交后团队共享 |
| 插件 | <plugin>/skills/<name>/SKILL.md | 启用插件处,以 /plugin-name:skill-name 调用 |
一个最小例子:
---
name: fix-issue
description: 按编号修复 GitHub issue
disable-model-invocation: true
---
按我们的编码规范修复 GitHub issue $ARGUMENTS。
1. 读 issue 描述
2. 实现修复
3. 写测试
4. 提交运行 /fix-issue 123,$ARGUMENTS 会替换成 123。
常用 frontmatter 字段:
| 字段 | 作用 |
|---|---|
description | 做什么、何时用。Claude 靠它判断要不要自动调用,所以把关键用途写在前面 |
disable-model-invocation | true 时 Claude 不会自己调用,只能你手动 /name |
user-invocable | false 时从 / 菜单隐藏,只给 Claude 用 |
allowed-tools | 本轮调用期间无需确认就能用的工具 |
argument-hint | 补全时提示参数,如 [issue-number] |
model / effort | 这个 skill 运行时用的模型 / 推理强度 |
context: fork | 在一个分叉出来的子代理里运行,配合 agent 指定子代理类型 |
paths | 只在处理匹配文件时自动加载 |
参数和变量:$ARGUMENTS 是全部参数,$0、$1(即 $ARGUMENTS[0])按位置取,${CLAUDE_SKILL_DIR} 是 skill 所在目录,${CLAUDE_SESSION_ID} 是会话 ID。
在 skill 里写 !`gh pr diff` 这样的语法,命令会在发给 Claude 之前先执行,输出替换进内容里,Claude 拿到的是真实数据。
在 skill 内容或提示词里写 ultrathink,会让那一轮做更深的推理。注意 think、think hard 这些早期流传的说法现在只是普通文字,不是关键词。
改了 skill 文件可以 /reload-skills,不用重启。
子代理(Subagents)
子代理在独立的上下文窗口里工作,只把结论带回来,适合「读一大堆文件但只要结论」的活。内置的有:
- Explore:只读,快速搜索和分析代码库,不加载 CLAUDE.md。
- Plan:计划模式下用来调研的只读代理。
- general-purpose:通用代理。
自定义子代理是一个 markdown 文件,放在 .claude/agents/(项目)或 ~/.claude/agents/(个人):
---
name: code-reviewer
description: 审查代码质量和最佳实践
tools: Read, Glob, Grep
model: sonnet
---
你是代码审查员。被调用时分析代码,给出关于质量、安全和最佳实践的具体建议。正文就是它的系统提示。只有 name 和 description 是必填,其他常用字段:tools / disallowedTools、model、permissionMode、maxTurns、skills(预加载 skill)、memory(给它开持久记忆)、isolation: worktree(在临时 worktree 里干活,没改动就自动清理)。
调用方式,从弱到强:
- 自然语言:「用 code-reviewer 子代理看看我最近的改动」,由 Claude 决定是否委派。
@提及:输入@从补全里选,或手写@agent-code-reviewer,保证一定用它。- 整个会话都以它运行:
claude --agent code-reviewer,或在.claude/settings.json里设"agent": "code-reviewer"。
不用改配置也能用:直接说「用子代理调查一下认证系统怎么刷新 token」,调研就不会占你主对话的上下文。
Hooks:确定性的自动化
CLAUDE.md 里写的是「建议」,Claude 可能不照做;hook 是 Claude Code 在特定时机一定会执行的命令。配置在 settings.json 的 hooks 下,分三层:事件 → matcher → 处理器。
官方的例子:拦截 rm -rf。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"if": "Bash(rm *)",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
"args": []
}
]
}
]
}
}#!/bin/bash
# .claude/hooks/block-rm.sh
COMMAND=$(jq -r '.tool_input.command')
if echo "$COMMAND" | grep -q 'rm -rf'; then
jq -n '{
hookSpecificOutput: {
hookEventName: "PreToolUse",
permissionDecision: "deny",
permissionDecisionReason: "Destructive command blocked by hook"
}
}'
else
exit 0
fihook 从 stdin 读到一段 JSON(工具名、参数等)。退出码的含义:0 成功,打印的 JSON 字段生效;2 是阻断性错误,在能阻断的事件上会拦下动作,stderr 作为原因;其他非零值是非阻断错误,动作照常进行。
常用事件:
| 事件 | 触发时机 |
|---|---|
SessionStart / SessionEnd | 会话开始(含恢复)/ 结束 |
UserPromptSubmit | 提交消息后、Claude 处理之前 |
PreToolUse | 工具调用之前,可以阻断 |
PostToolUse / PostToolUseFailure | 工具调用成功 / 失败之后,常用来自动格式化、跑 lint |
PermissionRequest | 需要权限决定时 |
Notification | Claude Code 发通知时(比如等你确认),可以接系统通知 |
Stop | Claude 回复结束时,可以用来「测试不过不许停」 |
SubagentStart / SubagentStop | 子代理启动 / 结束 |
PreCompact / PostCompact | 上下文压缩前后 |
完整列表还有 InstructionsLoaded、CwdChanged、FileChanged、WorktreeCreate、PreModelSwitch 等,一共三十多个,见 官方 hooks 文档。除了 command,处理器还可以是 HTTP 请求、MCP 工具、一段提示词或一个代理。用 /hooks 查看当前配置,不想手写可以用 /update-config,比如「每次改完文件都跑 prettier」。
MCP:接入外部工具
# 远程 HTTP 服务器(推荐)
claude mcp add --transport http notion https://mcp.notion.com/mcp
# 本地 stdio 服务器,-- 之后是启动命令
claude mcp add --env API_KEY=xxx --transport stdio myserver -- npx -y @example/mcp-server
# 直接给 JSON
claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'
claude mcp list # 列出所有服务器及连接状态
claude mcp get notion # 查看详情
claude mcp remove notion # 删除作用范围用 --scope(-s)指定:
| 范围 | 生效 | 共享 | 存在 |
|---|---|---|---|
local(默认) | 仅当前项目 | 否 | ~/.claude.json |
project | 仅当前项目 | 是,提交到 git | 项目根目录的 .mcp.json |
user | 所有项目 | 否 | ~/.claude.json |
会话里用 /mcp 看状态、做 OAuth 登录。MCP 服务器提供的 prompt 会变成斜杠命令,资源可以用 @server:resource 引用。
非交互模式:放进脚本和 CI
# 管道
cat build-error.txt | claude -p '简要解释这个构建错误的根因' > output.txt
# JSON 输出,用 jq 取结果
claude -p "总结这个项目" --output-format json | jq -r '.result'
# 预先放行工具
claude -p "跑测试并修复失败" --allowedTools "Bash,Read,Edit"
# 接着上一次对话
claude -p "现在重点看数据库查询" --continue
# 按会话 ID 续上
session_id=$(claude -p "开始评审" --output-format json | jq -r '.session_id')
claude -p "继续那次评审" --resume "$session_id"-p模式下需要审批的工具调用默认会被拒绝,所以要么--allowedTools预先放行,要么指定--permission-mode(如acceptEdits)。- 想要稳定的结构化结果,用
--json-schema;想实时流式处理,用--output-format stream-json --verbose。 - 加
--bare可以跳过 hooks、插件、CLAUDE.md 等的自动发现,启动更快,结果也不受本机配置影响。 -p会跳过工作区信任对话框,只在你信任的目录里用。
技巧清单
这些来自官方的 最佳实践 文档,加上我自己用下来的体会。
给 Claude 一个能自己跑的检查
我觉得这是最有用的一条。测试、构建退出码、lint、截图对比,任何能给出通过 / 不通过的东西都行。有了它,Claude 能自己反复改到通过;没有它,每个错误都要等你去发现。让它贴出证据:测试输出、跑了什么命令、返回了什么。想管得更严,可以用 /goal 设目标,或者用 Stop hook 在检查不过时不让它结束。
先探索,再计划,再写代码
大改动前 Shift+Tab 切到计划模式或 /plan,让它先读代码、出方案,你审过再动手,免得解决了错误的问题。
管好上下文
上下文窗口是最根本的限制,塞得越满,效果越差。
- 不相关的任务之间
/clear。 /compact 重点保留 X定向压缩;在 CLAUDE.md 里也可以写「压缩时始终保留改动过的文件列表和测试命令」。- 只想确认个细节,用
/btw,问答不进历史。 - 调研交给子代理,结论回来,过程不占主上下文。
/context看看是谁占了地方。
及早纠偏
看到方向不对就按 Esc 打断,已做的工作不会丢。纠正两次还不对,就 /clear,把学到的东西写进一条更好的初始提示重新来,别在被失败尝试污染的上下文里死磕。
失败了就回退
有检查点兜底,风险高一点的方案也可以让 Claude 先试,失败了 Esc Esc 退回去。Bash 命令造成的改动退不回来,这点要记着。
并行
claude -w name 开独立的 worktree 同时跑几个会话;/fork 复制一份到后台;/batch 把大规模迁移拆给一群子代理。
零碎的小技巧
- 写长提示词按
Ctrl+G在编辑器里写。 - 打到一半想先问别的,
Ctrl+S暂存,问完再按一次取回。 Ctrl+C误清了草稿,按Up找回来。- 命令跑得太久,
Ctrl+B丢到后台继续聊。 - 可以让 Claude 先采访你:「在动手之前,先就这个需求问我问题」。
- 新仓库第一次用:
/init生成 CLAUDE.md →/memory补充 →/permissions配好常用命令的放行,或者/fewer-permission-prompts自动生成。 - 提交前:
/diff看改动,/code-review找 bug,/simplify清理,/security-review查安全问题。 - 常见的失败模式:一个会话里什么都干(「厨房水槽」式会话);CLAUDE.md 写得过长;不给验证手段就信任输出;不设范围地「调查一下」,结果读了几百个文件。